Associate Social Account to User ID Process

Content

• Overview
• Process Flow
• App Settings
• Associate Social Account User Journey
• API Walkthroughs
• Error Codes
• Revision History

Overview

This process defines how an existing, authenticated ULM user links their existing ULM User ID with a social provider of their choice. This Process supports the OIDC standard protocol for authentication and authorization between relying parties.

Note: This process is distinct from the Onboard and Authenticate User with Social Account Process that starts from an anonymous (or unauthenticated) view. However, you can consult that topic's introduction sections for more information about how OIDC and third-party social provider association works in ULM Cloud.

Process Flow

The following tables describe the Social Connection Process functionality at a high level, when the Process is invoked from a social media connection flow.

App Settings

This Process currently has no relevant app settings to configure the Process behaviour.

Associate Social Account User Journey

This flow diagram illustrates the standard social association user journey using the Associate Social Account to User ID Process.

API Walkthroughs

This section provides guided walkthroughs of the Associate Social Account Process, including demonstrations of the various branching paths the Process can take during its execution.

Associate Social Account to Existing ULM User Scenario

In this flow, an authenticated user associates a trusted third-party social account to their user ID / user profile.

Initial Request

The Process Start API initializes the Process:

<no body>

Response

The Process prompts the user to select a social provider, from a list of available options:

{
    "processId": "13e6b3f4-7939-4fb7-a60f-cb09e852d430",
    "processName": "socialFederation.AssociateSocialMedia.v1.0",
    "displayMessage": "Please input required information",
    "parameters": {
        "providerId": "String"
    },
    "stepName": "ProviderPrompt",
    "lastStep": false,
    "output": {
        "providers": [
                "linkedin",
                "google",
                "facebook",
                "apple"
        ]
    }
}

Response Parameters

Next Request: Choose Social Provider

The user selects their desired social provider, and the client passes that info to the Process with the Process Step API:

{
    "processId": "13e6b3f4-7939-4fb7-a60f-cb09e852d430",
    "parameters": {
        "providerId": "facebook"
    }
}

Request Parameters

Response: Redirect URL to Social Provider

ULM responds with a redirect for the client to follow:

{
    "processId": "13e6b3f4-7939-4fb7-a60f-cb09e852d430",
    "processName": "socialFederation.AssociateSocialMedia.v1.0",
    "displayMessage": "Please input required information",
    "stepName": "CodePrompt",
    "lastStep": false,
    "output": {
        "requestUrl": "https://www.facebook.com/dialog/oauth?response_type=code&client_id=<redacted>
         &state=<redacted>&scope=public_profile%20email&redirect_uri=
         https%3A%2F%2Fidp-local.corp.amdocs.com%2Frest%2Fv70%2Fprocess%2Fstep"
    }
}

Response Parameters

Note: The client can skip this step if the social provider ID is provided in the initial Process Start request URL:

<no body>

The Process will then respond with the client redirect URL. This method is useful when social provider badges are displayed on a UI (for users to click and immediately begin association procedure).

Next Step: Redirect to Social Provider

Clients are expected to redirect to the URL provided in the requestUrl parameter. Users are typically asked to authenticate to their social profile, and then grant access for ULM to read basic information (their name, email address, etc). The social provider then redirects back to ULM Cloud with an authorization code, which ULM Cloud independently verifies with the social provider back-end.

<no body>

Response: Confirm Social Account Details

The Process then asks to confirm that this is the social account they wish to associate to their User ID:

{
    "processId": "13e6b3f4-7939-4fb7-a60f-cb09e852d430",
    "processName": "socialFederation.AssociateSocialMedia.v1.0",
    "displayMessage": "Please input required information",
    "parameters": {
        "confirm": "boolean",
        "lastName": "string",
        "firstName": "string",
        "displayName": "string",
        "phone": "string",
        "email": "string",
    },
    "stepName": "ConfirmAssociationPrompt",
    "lastStep": false,
    "output": {
        "providerId": "facebook",
        "socialUserInfo": {
            "id": "1425242407805720",
            "email": "bob@example.com",
            "firstName": "Bob",
            "lastName": "Jones"
        }
    }
}

Response Parameters

Final Request: Confirm Association

The user confirms the association, and the client passes that choice to the Process with the Process Step API.

{
    "processId": "13e6b3f4-7939-4fb7-a60f-cb09e852d430",
    "parameters": {
        "confirm": true,
        "lastName": "Jones",
        "firstName": "Bob",
        "email": "bob@example.com",
    }
}

Request Parameters

Response: Success, Account Associated to User ID

The Process completes the association and returns a 200 HTTP status code.

{
    "processId": "13e6b3f4-7939-4fb7-a60f-cb09e852d430",
    "processName": "socialFederation.AssociateSocialMedia.v1.0",
    "lastStep": true,
    "output": {
        "providerId":"facebook",
        "socialConnection": {
            "id": 1,
            "socialId": "1425242407805720",
            "providerId": "facebook"
        }
    }
}

The user now has the option to authenticate with the associated social account.

Response Parameters

Error Scenario: User Is Not Authenticated

If this Process is invoked without an authenticated user session, then the Process responds with a HTTP 400 status code. The body includes a operationError array with the reason(s) as to what went wrong:

{  
    operationError": {
        "code": "security-challenge-failed",
        "type": "com.uxpsystems.mint.framework.commons.exception.InsufficientPermissionException",
        "message": "Current user does not possess the correct authority to execute this ULM Process.",
        "authorities": [
            {
                "authority": "ROLE_ANONYMOUS"
            }
        ]
    }
}

Error Response Parameters

Error Codes

Below is a comprehensive list of potential error codes that may be returned during the execution of this Process.

Common Error Codes

Common Process Error Codes

Process-specific Error Codes

Revision History